一、基础功能使用
所有 XAPP SDK 的功能都是通过任务实现的，任务的使用是 XAPP SDK 的核心。
1、任务调用通用准则
XAPP SDK 的任务创建基本都是以 Builder 的形式进行创建，然后通过 startTask() 操作执行任务，取消任务可以通过 stopTask() 进行中止
//创建任务
Task task=***Task.newBuilder()
.setListener(listener)
.build();
//执行任务(异步)
XLinkSDk.startTask(task);
//中止任务
XLinkSDK.stopTask(task);
//或者取消直接对任务进行取消
task.cancel();在任务回调中，任务回调只要是TaskListener类型的接口都是允许的，该接口有四个抽象方法需要实现。
//任务执行错误（result.error != null）回调。注意此回调在task.onRetry()返回false后才会回调
void onError(Task<T> task, Throwable error);
//任务开始执行回调
void onStart(Task<T> task);
//任务重试时的回调
void onRetry(Task<T> task, T result);
//任务执行成功回调
void onComplete(Task<T> task, T result);一般情况下建议直接使用XLinkTaskListener抽象类，该类会将结果回调到主线程而不需要进行线程的切换工作。
//使用XLinkTaskListener时回调会在主线程中执行
Task task = ***Task.newBuilder()
.setListener(new XLinkTaskListener<T>{
@Override
public void onError(XLinkCoreException ex) {}
@Override
public void onStart() {}
@Override
public void onComplete(T result) {}
})实际使用场景 中onStart()与onRetry()的使用频率比较低，所以也可以使用此接口的空实现类TaskListenerAdapter直接仅重写需要的方法。
2、XAPP SDK用户授权登录
启动 XAPP SDK 后，若要使用云端服务相关操作（获取设备列表、通过云端获取数据端点、添加设备、删除设备等），需进行用户授权。其中用户授权分两种：
- 普通账号登录，即直接通过注册到物联云平台后台管理系统或者是部署私有云后注册使用的用户
- 第三方登录，包括但不限 QQ、微信等
不管通过哪种方式进行授权，最终都会获取到一些用户授权信息，建议开发者可以保存此部分信息以备用（根据实际的使用需求有可能不需要使用到，不需要使用时可以不保存）
2.1、普通账号授权
对于从平台注册的账号，需要使用普通账号授权任务进行登录操作并获取到授权信息。
XLinkUserAuthorizeTask task = XLinkUserAuthorizeTask.newBuilder()
// 手机号和密码
.setPhone(phone, password)
//邮箱和密码，setPhone和setEmail并没有实际的账号类型,都设置是允许的
.setEmail(email, password)
//企业ID
.setCorpId(corpId)
.setListener(new XLinkTaskListener<UserAuthApi.UserAuthResponse>() {
@Override
public void onError(XLinkCoreException xLinkErrorCode{
// 登录失败
}
@Override
public void onStart() {
}
@Override
public void onComplete(UserAuthApi.UserAuthResponse result) {
// 登录成功，在result中含有授权信息
// SDK内部自动进行云端连接
}
})
.build();2.2、第三方账号授权
第三账号授权任务一般是第三方账号接入云平台时的用户账号，该部分账号需要通过第三方账号登录授权任务登录，需要提供第三方账号相关的 openId、accessToken 和其它信息
XLinkThirdPartyAuthorizeTask task = XLinkThirdPartyAuthorizeTask.newBuilder()
// 第三方授权后获取的openId和accessToken
.setOpenId(openId)
.setAccessToken(accessToken)
//企业ID
.setCorpId(corpId)
//登录源,来源类型有以下几种
.setSource(XLinkRestfulEnum.UserSource.WEIXIN)
.setListener(new XLinkTaskListener<ThirdPartyAuthApi.AuthResponse>() {
@Override
public void onComplete(ThirdPartyAuthApi.AuthResponse result) {
// 登录成功，在result中含有授权信息
// SDK内部自动进行云端连接
}
})
.build();登录源,来源类型有以下几种
| 登录源 | 类型 |
|---|---|
| 网页 | XLinkRestfulEnum.UserSource.WEB |
| Android | XLinkRestfulEnum.UserSource.ANDROID |
| IOS | XLinkRestfulEnum.UserSource.IOS |
| 微信 | XLinkRestfulEnum.UserSource.WEIXIN |
| XLinkRestfulEnum.UserSource.QQ | |
| 微博 | XLinkRestfulEnum.UserSource.WEIBO |
| XLinkRestfulEnum.UserSource.FACEBOOK | |
| XLinkRestfulEnum.UserSource.TWITTER | |
| 其它来源 | XLinkRestfulEnum.UserSource.OTHER |
注意：由于 XAPP SDK 内部需要授权信息，请使用 XAPP SDK 提供的授权接口进行授权，不要自行通过 Restful 进行用户授权
2.3、手机短信登录授权
手机短信登录授权是方便用户通过手机接收验证码快速登录的功能，并且 SDK 在用户登录成功后将使用用户信息自行进行云端连接操作。推荐需要实现短信登录功能时，直接使用此任务。
- 获取手机短信验证码
XLinkThirdPartyAuthorizeTask task = XLinkThirdPartyAuthorizeTask.newBuilder()
// 第三方授权后获取的openId和accessToken
.setOpenId(openId)
.setAccessToken(accessToken)
//企业ID
.setCorpId(corpId)
//登录源,来源类型有以下几种
.setSource(XLinkRestfulEnum.UserSource.WEIXIN)
.setListener(new XLinkTaskListener<ThirdPartyAuthApi.AuthResponse>() {
@Override
public void onComplete(ThirdPartyAuthApi.AuthResponse result) {
// 登录成功，在result中含有授权信息
// SDK内部自动进行云端连接
}
})
.build();- 通过短信登录任务进行登录
XLinkSmsAuthorizeTask task = XLinkSmsAuthorizeTask.newBuilder()
.setCorpId(corpId)
.setPhone(phone)
//设置手机的区号，默认为+86中国大陆，可选参数
.setPhoneZone(phoneZone)
//手机验证码
.setVerifyCode(captcha)
.setListener(new XLinkTaskListener<UserAuthApi.UserSmsAuthResponse>() {
@Override
public void onComplete(UserAuthApi.UserSmsAuthResponse result) {
// 登录成功，在result中含有授权信息
// SDK内部自动进行云端连接
}
})
.build();
XLinkSDK.startTask(task);**
注意：获取手机短信登录验证码的接口依然需要通过 XLinkRestful 调用**
3、设备操作
除了用户登录操作，XAPP SDK 中最重要的就是与设备通讯的任务了。一般情况下会包含以下几个任务：
| 任务名称 | 任务意义 | 任务作用 |
|---|---|---|
| XLinkScanDeviceTask | 扫描设备任务 | 扫描同一局域网内的设备以便后续添加订阅和连接 |
| XLinkAddDeviceTask | 添加订阅设备任务 | 添加设备，并将设备与用户关联绑定关系，实现任何情况下用户可同步并使用设备 |
| XLinkSyncDeviceListTask | 同步设备任务 | 同步与用户关联的设备列表信息 |
| XLinkRemoveDeviceTask | 移除设备任务 | 移除设备并取消用户与设备之前的关联关系 |
| XLinkGetDataPointTask | 获取设备数据端点任务 | 获取设备数据的任务 |
| XLinkSetDataPointTask | 设置设备数据端点任务 | 设置设备数据的任务 |
3.1、扫描设备任务
对于一个全新的设备，需要通过扫描局域网内的设备发现设备，再进行后续的操作。这是设备操作的首要步骤。
XLinkScanDeviceTask scanTask = XLinkScanDeviceTask.newBuilder()
// 设置超时，单位毫秒，根据需要可适当调整
.setTotalTimeout(45000)
//设置扫描的目标PID,可同时设置多个,不支持null与空字符串
.setProductIds(pid1,pid2)
//设置搜索回调,回调在主线程上执行
.setScanDeviceListener(new XLinkScanDeviceListener() {
@Override
public void onScanResult(XDevice xDevice) {
// 同一设备仅会回调一次
}
@Override
public void onError(XLinkCoreException xLinkErrorCode) {
}
@Override
public void onStart() {
}
@Override
public void onComplete(Void aVoid) {
}
}).build();**
扫描设备操作仅通过setScanDeviceListener设置扫描回调，不需要设置setListener**
注意：扫描设备时需要一些条件限制，请务必确认处于相应环境下才能正常扫描到设备
- APP 与扫描的设备必须在同一局域网中
- 确认设备版本与 APP 支持的版本兼容
注意事项：若扫描不到设备并无法确认原因，可查看 [FAQ](../Android SDK开发指南/A-FAQ.md) 相关问题解答
3.2、添加订阅设备
添加设备是通过内网与设备通过后，再将校验信息提交到云端，通过云端的校验后将设备与用户形成绑定关系。成功订阅过的设备将在同步设备列表时可以同步到。
XLinkAddDeviceTask task = XLinkAddDeviceTask.newBuilder()
//设置需要添加的设置,一般来自扫描得到的设备对象
.setXDevice(device)
//是否在添加成功后进行设备内网连接
.setConnectLocal(true)
//是否在添加成功后订阅设备
.setNeedSubscription(true)
//设置本次订阅任务的回调
.setListener(xxxx)
.build();注意事项：已添加成功的设备，XAPP SDK 会自动在云端建立当前用户账号与设备的订阅关系，并用于后续的数据更新和同步，具体请参考下文的“同步设备”。
关于添加与订阅的差异如下:
| 操作 | 说明 | 影响 |
|---|---|---|
| 添加设备 | 添加设备为 XAPP SDK 与设备之前建立起联系并从设备获取到部分设备信息(可用于校验工作) | 添加是正常情况下使用设备的前提条件，但是添加操作与云端及用户无直接关联 |
| 订阅设备 | 通过云端提交设备信息,云端在校验成功后将设备与当前用户绑定关系 | 订阅是保存用户与设备之间关系的必要操作，只有订阅后的设备才能进行远程同步及控制 |
注：默认情况下，XLinkAddDeviceTask任务是包括了添加设备及订阅设备两部分操作。
3.3、同步设备任务
同步设备任务用于将将当前用户的设备设备从云端同步到内网。任务完成后默认自动发起内网连接和云端连接, 同步后的设备会自动添加到设备维护列表中进行维护，设备状态变更时也会有相应的状态回调。
XLinkSyncDeviceListTask task = XLinkSyncDeviceListTask.newBuilder()
//同步设备后是否需要进行内网连接,默认为true,v6.2版本起默认为false
.setConnectLocal(false)
//设置同步设备的监听事件
.setListener(xxx)
.build();同步设备要求设备和当前用户之间有订阅关系，无订阅关系无法同步到设备。若设备与 APP 在同一局域网，一般建议设置启用内网连接 setConnectLocal(true) 。完全不需要依赖内网通讯的，建议关闭内网连接setConnectLocal(false)，以减少部分资源的维护成本与性能消耗。
3.4、移除设备
移除设备成功时，XAPP SDK 会自动从云端解除当前用户与设备之间的订阅关系，并删除与该设备相关的共享和访问权限, 同时也会将该设备移除维护列表, 设备将不能再使用。
XLinkRemoveDeviceTask removeDeviceTask = XLinkRemoveDeviceTask.newBuilder()
//需要删除的设备,可以通过XLinkDeviceManager获取到对应的设备
.setXDevice(device)
.setListener(xxx)
.build();3.5、获取设备物模型
对设备的控制实际上就是对设备的物模型进行操作，从而达到设备状态或行为变化。其中获取设备物模型使用XLinkTMLProbeAttributeTask
// 查询设备物模型
XLinkTMLProbeAttributeTask.newBuilder()
.setSendPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
.setXDevice(xDevice)
.setListener(xxx)
.build();获取设备物模型之前需要配置物模型的监听，即setTMLAttributeListener。因为获取到的数据将会通过上报的形式给到App。请查看 FAQ 相关问题解答
3.6、设置设备物模型属性
对设备的控制实际上就是对设备的物模型进行操作，从而达到设备状态或行为变化。其中设置设备物模型使用XLinkTMLSetAttributeTask
//快速转换成json数据的物模型参数
String content = new TMLAttributeRequestBuilder()
.addInput("scene_id", sceneId)
.toJsonString();
// 设置设备的物模型
XLinkTMLSetAttributeTask.newBuilder()
.setSendPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
.setXDevice(xDevice)
.setTmlDataPayload(content)
.setListener(xxx)
.build(); 3.7、调用设备物模型服务
相比于属性，服务可通过一条指令实现更复杂的业务逻辑。其中调用设备物模型服务使用XLinkTMLInvokeServiceTask
// 调用设备的物模型服务
XLinkTMLInvokeServiceTask.newBuilder()
.setSendPolicy(XLinkSendDataPolicy.LOCAL_ONLY)
.setXDevice(xDevice)
.setTmlServiceName(ProtocolConstant.TML_SERVICE_EXECUTE_SCENE)
.setTmlDataPayload(content)
.setListener(xxx)
.build(); 二、更新说明
| 日期 | 更新内容 |
|---|---|
| 2019-05-11 | 新增短信登录任务的使用说明 |
| 2019-01-15 | 文本更新校准 |
